package ezXpns.storage;

import java.io.IOException;
import java.util.Map.Entry;
import java.util.UUID;

/**
 * Interface for a storage engine
 * @param <T> the value type
 */

//@author A0088827L
public interface StorageEngine<T> {
	/**
	 * Add a new object to this storage
	 * Add should be idempotent. That is, adding the same {id, obj} pair multiple times should
	 * not change the storage.
	 * @param id id of the object to add
	 * @param obj the object
	 */
	public void add(UUID id, T obj);
	
	/**
	 * Remove an object from the storage
	 * @param id id of the object to be removed
	 * @return the removed object or null if nothing is removed
	 */
	public T remove(UUID id);
	
	/**
	 * Replace an object with a new one iff it exists
	 * @param id id of the object to be replaced
	 * @param newObj the new object
	 * @return the old object or null if it's not replaced
	 */
	public T replace(UUID id, T newObj);
	
	/**
	 * Search for an object by id
	 * @param id id of the object
	 * @return the object or null if no object with such id exists
	 */
	public T get(UUID id);
	
	/**
	 * Retrieve all entries
	 * @return a stream of {id, object} pairs
	 */
	public Iterable<Entry<UUID, T>> getAllEntries();
	
	/**
	 * Force save data
	 * @throws IOException
	 */
	public void save() throws IOException;
	
	/**
	 * Close the engine, persist all unsaved data
	 * The engine must not be used again
	 * All locks (if any) must be released after this point
	 * 
	 * @throws IOException
	 */
	public void close() throws IOException;
}